Drawing State Methods

DESCRIPTION

The kQ3XMethodTypeRendererStartFrame method type returns a function pointer of type TQ3XRendererStartFrameMethod.

TQ3XRendererStartFrameMethod is first called from Q3View_StartRendering . It should perform these tasks:

• initialize any renderer states to their default values
• extract all useful data from the drawContext object
• if the renderer passed in kQ3RendererFlagClearBuffer at registration, it should also clear the draw context.
• clear the drawContext object

When clearing the drawContext object, the renderer may opt to use any one of these procedures:

• not clear anything (for example, if it already touches every pixel)
• clear with its own routine, or
• use the draw context default clear method by calling Q3DrawContext_Clear . Q3DrawContext_Clear takes advantage of any hardware in the system that is available for clearing the drawing context.

TQ3XRendererStartFrameMethod also signals the beginning of receiving default submit commands from the view. The renderer will receive updates for the default view state via its update methods before StartScene is called. Renderer submit and update methods are discussed on [link] .

DESCRIPTION

The kQ3XMethodTypeRendererStartPass method type returns a function pointer of type TQ3XRendererStartPassMethod.

TQ3XRendererStartPassMethod is called during Q3View_StartRendering after the StartFrame command. It should perform these tasks:

• collect camera and light information
• prepare any additional states before object submit calls are made

If the renderer supports deferred camera transformation, camera represents the main camera that will be submitted somewhere in the hierarchy. Its value is never NULL . If your renderer does not support deferred camera transformation, camera represents the transformed camera.

If the renderer supports deferred light transformation, the value of lightGroup will be NULL and it will be submitted to your light draw methods instead.

Calling TQ3XRendererStartPassMethod signals the end of the default update state and the start of submit commands from the user to the view.

DESCRIPTION

The kQ3XMethodTypeRendererFlushFrame method type returns a function pointer of type TQ3XRendererFlushFrameMethod.

TQ3XRendererFlushFrameMethod is called between the StartScene and EndScene methods. It is called when the user wishes to flush any asynchronous drawing tasks that draw to the drawContext object, but does not want to block asynchronous drawing altogether. As a result, an image should eventually appear asynchronously. In asynchronous rendering, this call is non-blocking.

An interactive renderer should ensure that all received geometries are drawn in the image. If it controls the hardware, it should force the hardware to generate an image.

A deferred renderer should exhibit similar behavior, though this is not a requirement. A deferred renderer should spawn a process that generates a partial image from the currently accumulated drawing state.

Implementing TQ3XRendererFlushFrameMethod is not recommended for computation-intensive renderers such as ray-tracers.

DESCRIPTION

The kQ3XMethodTypeRendererEndPass method type returns a function pointer of type TQ3XRendererEndPassMethod.

TQ3XRendererEndPassMethod is called at Q3View_EndRendering and signals the end of sending submit commands to the view. If the renderer requires another pass on the data being rendered, it should return kQ3ViewStatusRetraverse .

If rendering was cancelled, TQ3XRendererEndPassMethod will not be called and the view will return kQ3ViewStatusCancelled . Otherwise, your renderer should initiate completion of the process of generating the image in the drawing context. If it has buffered any drawing data, the data must be flushed. TQ3XRendererEndPassMethod should have an effect similar to that of FlushFrame .

A synchronous renderer must update the front buffer; otherwise DrawContext will update the front buffer after returning. If a synchronous renderer supports kQ3RendererClassSupportDoubleBuffer , it must finish rendering the entire frame.

An asynchronous renderer must spawn a rendering thread for the entire frame. If it supports kQ3RendererClassSupportDoubleBuffer , it must eventually either update the front buffer asynchronously, then call Q3View_EndFrame , or update the back buffer asynchronously, then call Q3View_EndFrame .

If an error occurs with TQ3XRendererEndPassMethod, the renderer should call Q3Error_Post and return kQ3ViewStatusError .

DESCRIPTION

The kQ3XMethodTypeRendererEndFrame method type returns a function pointer of type TQ3XRendererEndFrameMethod.

TQ3XRendererEndFrameMethod is called from Q3View_Sync , which is called after Q3View_EndRendering . It signals that the user wishes to see the completed image and is willing to block drawing. No call to Q3View_EndFrame is needed.

If your renderer supports kQ3RendererFlagDoubleBuffer , it must update the front buffer completely; otherwise it must update the back buffer completely.

TQ3XRendererEndFrameMethod is equivalent in functionality to FlushFrame , but it blocks drawing until the image is completed.

If TQ3XRendererEndFrameMethod is not supplied, the default action is no operation.

Registering a method of type TQ3XRendererEndFrameMethod indicates that your renderer will continue rendering after Q3View_EndRendering has been called.

DESCRIPTION

The kQ3XMethodTypeRendererCancel method type returns a function pointer of type TQ3XRendererCancelMethod.

TQ3XRendererCancelMethod is called after Q3View_StartRendering and signals the termination of all rendering operations. Your renderer should clean up any cached data and cancel all rendering operations.

If TQ3XRendererCancelMethod is called before Q3View_EndRendering , TQ3XRendererEndPassMethod is not called.

If TQ3XRendererCancelMethod is called after Q3View_EndRendering , your renderer should kill any rendering threads and terminate any further rendering. If your renderer is asynchronous, TQ3XRendererCancelMethod will never be called after Q3View_EndRendering .